// Copyright (C) ZHENG Zhong <heavyzheng nospam-at gmail D0T com>
// http://www.zhengzhong.net/
//
// $Id: content_handler.hpp 318 2009-03-02 14:03:21Z heavyzheng $
//

#ifndef ZZHENG_XML_SAX_CONTENT_HANDLER_HPP_20090122__
#define ZZHENG_XML_SAX_CONTENT_HANDLER_HPP_20090122__

#include <zzheng/xml/config.hpp>
#include <zzheng/xml/sax/types.hpp>
#include <zzheng/xml/sax/handler_tag.hpp>
#include <zzheng/xml/sax/attribute.hpp>

#include <string>


namespace zzheng {
namespace xml {
namespace sax {

    //! This class defines the interface for handling XML content. It defines callback functions
    //! that will be invoked by the XML SAX parser. User should derive from this class to provide
    //! customized handling functions.
    class content_handler {

    public:

        typedef content_handler_tag handler_category;

    public:

        //! Default constructor.
        explicit content_handler() {
            // Do nothing.
        }

        //! Virtual destructor that makes this class derivable.
        virtual ~content_handler() {
            // Do nothing.
        }

        //! Receives notification of the beginning of an XML document. The SAX parser will invoke
        //! this function only once, before any other event callbacks.
        virtual void begin_doc() = 0;

        //! Receives notification of the end of an XML document. The SAX parser will invoke this
        //! function only once (in case no fatal error occurs), and it will be the last function
        //! invoked during the parse.
        virtual void end_doc() = 0;

        //! Receives notification of the beginning of a namespace scope. Note that begin_ns/end_ns
        //! events are not guaranteed to be properly nested relative to each other: all begin_ns
        //! events will occur immediately before the corresponding begin_elem event, and all end_ns
        //! events will occur immediately after the corresponding end_elem event, but their order
        //! is not otherwise guaranteed.
        //!
        //! There should never be begin_ns/end_ns events for the "xml" prefix, since it is
        //! predeclared and immutable.
        //!
        //! \param prefix  the namespace prefix being declared. An empty string is used for the
        //!                default element namespace, which has no prefix.
        //! \param uri     the namespace URI the prefix is mapped to.
        virtual void begin_ns(const std::string& prefix, const std::string& uri) = 0;

        //! Receives notification of the end of a namespace scope.
        //! \param prefix  the namespace prefix that was being mapped, or an empty string when a
        //!                default mapping scope ends.
        virtual void end_ns(const std::string& prefix) = 0;

        //! Receives notification of the beginning of an element.
        //! \param name   the local name of this element.
        //! \param uri    the namespace URI of this element.
        //! \param qname  the qualified (prefixed) name of this element.
        //! \param attrs  the attribute list associated with this element.
        virtual void begin_elem(const std::string& name,
                                const std::string& uri,
                                const std::string& qname,
                                const attribute_list& attrs) = 0;

        //! Receives notification of the end of an element.
        //! \param name   the local name of this element.
        //! \param uri    the namespace URI of this element.
        //! \param qname  the qualified (prefixed) name of this element.
        virtual void end_elem(const std::string& name,
                              const std::string& uri,
                              const std::string& qname) = 0;

        virtual void characters(const char* chars, size_type start, size_type length) = 0;

        virtual void ignorable_whitespace(const char* chars, size_type start, size_type length) = 0;

        //! Receives notification of an XML comment.
        //! \param chars  the XML comment.
        //! \param start  the starting position in the XML comment.
        //! \param length  the length of the XML comment.
        virtual void comment(const char* chars, size_type start, size_type length) = 0;

    }; // class content_handler


} // namespace zzheng::xml::sax
} // namespace zzheng::xml
} // namespace zzheng


#endif // ZZHENG_XML_SAX_CONTENT_HANDLER_HPP_20090122__





